Notification#

The Notification module in the Scripting app allows you to schedule, manage, and display local notifications with advanced trigger types, interactive actions, and rich UI capabilities.

Table of Contents#

1. Scheduling Notifications

2. Notification Triggers

   • TimeIntervalNotificationTrigger
   • CalendarNotificationTrigger
   • LocationNotificationTrigger

3. Notification Actions

4. Rich Notifications with Custom UI

5. Managing Notifications

6. NotificationInfo and Request Structure

7. Comprehensive Example

Scheduling Notifications#

Use Notification.schedule to schedule a local notification. It supports content, triggers, tap behaviors, action buttons, rich UI, and delivery configurations:

1await Notification.schedule({
2  title: "Reminder",
3  body: "Time to stand up!",
4  trigger: new TimeIntervalNotificationTrigger({
5    timeInterval: 1800,
6    repeats: true
7  }),
8  actions: [
9    {
10      title: "OK",
11      url: Script.createRunURLScheme("My Script", { acknowledged: true })
12    }
13  ],
14  tapAction: {
15    type: "runScript",
16    scriptName: "Acknowledge Script"
17  },
18  customUI: false
19})

Parameters#

Deprecated: triggerTime and repeatsType are deprecated. Use trigger instead.

Tap Behavior (tapAction)#

The tapAction parameter gives you precise control over what happens when the user taps the notification:

• "none" – Do nothing when tapped
• { type: "runScript", scriptName: string } – Run a different script
• { type: "openURL", url: string } – Open a deep link or web page

If tapAction is not provided, the default behavior is to run the current script, and the notification details can be accessed using Notification.current.

Notification Triggers#

TimeIntervalNotificationTrigger#

Triggers a notification after a specified number of seconds.

1new TimeIntervalNotificationTrigger({
2  timeInterval: 3600,
3  repeats: true
4})

• timeInterval: Delay in seconds
• repeats: Whether it repeats
• nextTriggerDate(): Returns the next expected trigger date

CalendarNotificationTrigger#

Triggers when the current date matches specific calendar components.

1const components = new DateComponents({ hour: 8, minute: 0 })
2new CalendarNotificationTrigger({
3  dateMatching: components,
4  repeats: true
5})

• Supports components like year, month, day, hour, etc.
• Useful for daily or weekly reminders

LocationNotificationTrigger#

Triggers when entering or exiting a geographic region.

1new LocationNotificationTrigger({
2  region: {
3    identifier: "Work",
4    center: { latitude: 37.7749, longitude: -122.4194 },
5    radius: 100,
6    notifyOnEntry: true,
7    notifyOnExit: false
8  },
9  repeats: false
10})

• Fires based on entering/exiting the specified circular region

Notification Actions#

Use the actions array to define buttons shown when the notification is expanded:

1actions: [
2  {
3    title: "Open Details",
4    url: Script.createRunURLScheme("Details Script", { fromNotification: true })
5  },
6  {
7    title: "Dismiss",
8    url: Script.createRunURLScheme("Dismiss Script", { dismissed: true }),
9    destructive: true
10  }
11]

• Use Script.createRunURLScheme(...) to generate Scripting app URLs
• Action buttons appear on long-press or pull-down

Rich Notifications with Custom UI#

You can provide an interactive JSX interface:

1. Set customUI: true in the Notification.schedule() call
2. Create a notification.tsx file
3. Call Notification.present(element) inside that file

Notification.present(element: JSX.Element): void#

Must be called from notification.tsx. Renders the element as the expanded notification interface.

Example notification.tsx#

1import { Notification, VStack, Text, Button } from 'scripting'
2
3function NotificationView() {
4  return (
5    <VStack>
6      <Text>Need to complete your task?</Text>
7      <Button title="Done" action={() => console.log("Task completed")} />
8      <Button title="Later" action={() => console.log("Task postponed")} />
9    </VStack>
10  )
11}
12
13Notification.present(<NotificationView />)

Managing Notifications#

NotificationInfo and Request Structure#

Use Notification.current to get launch context when the script is opened from a notification tap:

1if (Notification.current) {
2  const { title, userInfo } = Notification.current.request.content
3  console.log(`Launched from: ${title}`, userInfo)
4}

NotificationRequest Fields#

Comprehensive Example#

This example demonstrates a full-featured notification with actions, rich UI, and repeated delivery.

Step 1: Schedule the Notification#

1await Notification.schedule({
2  title: "Hydration Reminder",
3  body: "Time to drink water!",
4  interruptionLevel: "timeSensitive",
5  customUI: true,
6  trigger: new TimeIntervalNotificationTrigger({
7    timeInterval: 3600,
8    repeats: true
9  }),
10  tapAction: {
11    type: "runScript",
12    scriptName: "Hydration Tracker"
13  },
14  actions: [
15    {
16      title: "I Drank",
17      url: Script.createRunURLScheme("Hydration Tracker", { drank: true }),
18    },
19    {
20      title: "Ignore",
21      url: Script.createRunURLScheme("Hydration Tracker", { drank: false }),
22      destructive: true
23    }
24  ]
25})

Step 2: Define notification.tsx#

1import { Notification, VStack, Text, Button } from 'scripting'
2
3function HydrationUI() {
4  return (
5    <VStack>
6      <Text>Have you drunk water?</Text>
7      <Button title="Yes" action={() => console.log("Hydration confirmed")} />
8      <Button title="No" action={() => console.log("Reminder ignored")} />
9    </VStack>
10  )
11}
12
13Notification.present(<HydrationUI />)

Summary#

The Notification API in the Scripting app supports:

• Time, calendar, and location-based triggers
• Actionable buttons and script redirection
• Tap behaviors via tapAction
• Rich notification UI via notification.tsx
• Full lifecycle management (deliver, remove, query)

For future compatibility, always prefer the trigger and tapAction parameters over deprecated ones like triggerTime and avoidRunningCurrentScriptWhenTapped.